<!DOCTYPE html>
<html lang="zh">

<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
	<meta name="keywords" content="dromara.org" />
	<meta name="description" content="dromara.org" />
	<!-- 网页标签标题 -->
	<title>dromara(Open source organization)</title>
	<link rel="shortcut icon" href="/website/img/docsite.ico"/>
	<link rel="stylesheet" href="/website/build/documentation.css" />
</head>
<body>
	<div id="root"><div class="documentation-page" data-reactroot=""><header class="header-container header-container-normal"><div class="header-body"><a href="/website/en-us/index.html"><img class="logo" src="/website/img/dromara.png"/></a><div class="search search-normal"><span class="icon-search"></span></div><span class="language-switch language-switch-normal">中</span><div class="header-menu"><img class="header-menu-toggle" src="/website/img/system/menu_gray.png"/><ul><li class="menu-item menu-item-normal"><a href="/website/en-us/index.html" target="_self">Home</a><div class="sub-menu"><ul></ul></div></li><li class="menu-item menu-item-normal menu-item-normal-active"><a href="#">Document</a><div class="sub-menu"><ul><li><a href="/website/en-us/docs/soul/soul.html" target="_self">Soul</a></li><li><a href="/website/en-us/docs/hmily/index.html" target="_self">Hmily</a></li></ul></div></li><li class="menu-item menu-item-normal"><a href="/website/en-us/blog/index.html" target="_self">Blog</a><div class="sub-menu"><ul></ul></div></li><li class="menu-item menu-item-normal"><a href="/website/en-us/community/index.html" target="_self">Community</a><div class="sub-menu"><ul></ul></div></li></ul></div></div></header><section class="content-section"><div class="sidemenu" id="menu"><div class="sidemenu-toggle"><img src="https://img.alicdn.com/tfs/TB1E6apXHGYBuNjy0FoXXciBFXa-200-200.png"/></div><ul><li class="menu-item menu-item-level-1"><span>Soul</span><ul><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/website/en-us/docs/soul/soul.html" target="_self">Home  </a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/website/en-us/docs/soul/team.html" target="_self">Team</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/website/en-us/docs/soul/db.html" target="_self">Database Design</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/website/en-us/docs/soul/config.html" target="_self">Config</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/website/en-us/docs/soul/dataSync.html" target="_self">DataSync</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/website/en-us/docs/soul/metaData.html" target="_self">MetaData</a></li><li style="height:612px;overflow:hidden" class="menu-item menu-item-level-2"><span>User Document<img style="transform:rotate(0deg)" class="menu-toggle" src="/website/img/system/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/setup.html" target="_self">Set up</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/user-http.html" target="_self">Http proxy</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/user-dubbo.html" target="_self">Dubbo proxy</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/user-springcloud.html" target="_self">Spring cloud proxy</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/selector.html" target="_self">Selector and Rule</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/user-dataSync.html" target="_self">Use data sync</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-divide.html" target="_self">Divide Plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-dubbo.html" target="_self">Dubbo plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-springcloud.html" target="_self">Spring cloud plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-rateLimiter.html" target="_self">RateLimiter plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-hystrix.html" target="_self">Hystrix plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-monitor.html" target="_self">Monitor plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-waf.html" target="_self">Waf plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-sign.html" target="_self">Sign plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-rewrite.html" target="_self">Rewrite plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/plugin-websocket.html" target="_self">Websocket plugin</a></li></ul></li><li style="height:360px;overflow:hidden" class="menu-item menu-item-level-2"><span>Developer Guide<img style="transform:rotate(0deg)" class="menu-toggle" src="/website/img/system/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-filter.html" target="_self">Custom filter </a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-plugin.html" target="_self">Custom plugin</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-file.html" target="_self">File and Image</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-iphost.html" target="_self">Custom parsing IP and Host</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-result.html" target="_self">Custom result</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-sign.html" target="_self">Custom sign algorithm</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-client.html" target="_self">Developer soul client</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-thread.html" target="_self">Thread</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/dev-netty.html" target="_self">Soul optimize</a></li></ul></li><li style="height:144px;overflow:hidden" class="menu-item menu-item-level-2"><span>Community<img style="transform:rotate(0deg)" class="menu-toggle" src="/website/img/system/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/contributor.html" target="_self">Contributor</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/committer.html" target="_self">Committer</a></li><li class="menu-item menu-item-level-3"><a href="/website/en-us/docs/soul/code-conduct.html" target="_self">Code conduct</a></li></ul></li></ul></li></ul></div><div class="doc-content markdown-body" id="doc-body"><h2>Features</h2>
<ul>
<li>
<p>this article is a guide about how to integrate Spring Cloud with soul gateway quickly.</p>
</li>
<li>
<p>pls enable <code>springCloud</code> plug-in in soul-admin background.</p>
</li>
<li>
<p>Pls start <code>soul-admin</code> successfully beofore integrating , and <a href="setup.md">Environement Setup</a> is Ok.</p>
</li>
</ul>
<h2>Configure soul gateway as Spring Cloud proxy</h2>
<ul>
<li>add these dependencies in gateway's pom.xml:</li>
</ul>
<pre><code class="language-xml">  <span class="hljs-comment">&lt;!--soul springCloud plugin start--&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>org.dromara<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>soul-spring-boot-starter-plugin-springcloud<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>${last.version}<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
  <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span>
   <span class="hljs-comment">&lt;!--soul springCloud plugin end--&gt;</span>

   <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>org.springframework.cloud<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>spring-cloud-commons<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>2.2.0.RELEASE<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
   <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span> 
   <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>org.springframework.cloud<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>spring-cloud-starter-netflix-ribbon<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>2.2.0.RELEASE<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
   <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span>
</code></pre>
<ul>
<li>
<p>If you use <code>eureka</code> as SpringCloud registry center.</p>
<ul>
<li>add these dependencies:</li>
</ul>
</li>
</ul>
<pre><code class="language-xml">  <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>org.springframework.cloud<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>spring-cloud-starter-netflix-eureka-client<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>2.2.0.RELEASE<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
  <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span>
</code></pre>
<ul>
<li>add these config values in gateway's yaml file:</li>
</ul>
<pre><code class="language-yaml">   <span class="hljs-attr">eureka:</span>
     <span class="hljs-attr">client:</span>
       <span class="hljs-attr">serviceUrl:</span>
         <span class="hljs-attr">defaultZone:</span> <span class="hljs-string">http://localhost:8761/eureka/</span> <span class="hljs-comment">#your eureka address</span>
     <span class="hljs-attr">instance:</span>
       <span class="hljs-attr">prefer-ip-address:</span> <span class="hljs-literal">true</span>
</code></pre>
<ul>
<li>
<p>if you use <code>nacos</code> as Spring Cloud registry center.</p>
<ul>
<li>add these dependencies:</li>
</ul>
</li>
</ul>
<pre><code class="language-xml"> <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>com.alibaba.cloud<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>spring-cloud-starter-alibaba-nacos-discovery<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
       <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>2.1.0.RELEASE<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
 <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span>
</code></pre>
<ul>
<li>add these config values in gateway's yaml file:</li>
</ul>
<pre><code class="language-yaml">  <span class="hljs-attr">spring:</span>
     <span class="hljs-attr">cloud:</span>
       <span class="hljs-attr">nacos:</span>
         <span class="hljs-attr">discovery:</span>
            <span class="hljs-attr">server-addr:</span> <span class="hljs-number">127.0</span><span class="hljs-number">.0</span><span class="hljs-number">.1</span><span class="hljs-string">:8848</span> <span class="hljs-comment"># your nacos address</span>
</code></pre>
<ul>
<li>restart your gateway service.</li>
</ul>
<h2>SpringCloud integration with gateway.</h2>
<ul>
<li>add these dependencies in your project：</li>
</ul>
<pre><code class="language-xml"> <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
      <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>org.dromara<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
      <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>soul-spring-boot-starter-client-springcloud<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
      <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>${last.version}<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
 <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span>
</code></pre>
<ul>
<li>add these config values in your yaml file:</li>
</ul>
<pre><code class="language-yaml"><span class="hljs-attr">soul:</span>
  <span class="hljs-attr">springcloud:</span>
    <span class="hljs-attr">admin-url:</span> <span class="hljs-string">http://localhost:9095</span>
    <span class="hljs-attr">context-path:</span> <span class="hljs-string">/springcloud</span>
    <span class="hljs-attr">appName:</span> <span class="hljs-string">http</span>
<span class="hljs-comment"># adminUrl: 'ip + port' of your soul-admin project, pls note 'http://' is necessary.</span>
<span class="hljs-comment"># contextPath: your project's route prefix through soul gateway, such as /order ，/product etc，gateway will route based on it.</span>
<span class="hljs-comment"># appName：your project name,the default value is`spring.application.name`.</span>
</code></pre>
<ul>
<li>
<p>add the annotation <code>@SoulSpringCloudClient</code> in your <code>controller</code> interface.</p>
</li>
<li>
<p>you can apply the annotation to class-level in a controller.the name of the path variable is prefix and '/**' will apply proxy for entire interfaces.</p>
<ul>
<li>example （1）：both <code>/test/payment</code> and <code>/test/findByUserId</code> will be handled by gateway.</li>
</ul>
</li>
</ul>
<pre><code class="language-java"> <span class="hljs-meta">@RestController</span>
 <span class="hljs-meta">@RequestMapping</span>(<span class="hljs-string">"/test"</span>)
 <span class="hljs-meta">@SoulSpringCloudClient</span>(path = <span class="hljs-string">"/test/**"</span>)
 <span class="hljs-keyword">public</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">HttpTestController</span> </span>{
     
     <span class="hljs-meta">@PostMapping</span>(<span class="hljs-string">"/payment"</span>)
     <span class="hljs-function"><span class="hljs-keyword">public</span> UserDTO <span class="hljs-title">post</span><span class="hljs-params">(@RequestBody <span class="hljs-keyword">final</span> UserDTO userDTO)</span> </span>{
         <span class="hljs-keyword">return</span> userDTO;
     }
     
     <span class="hljs-meta">@GetMapping</span>(<span class="hljs-string">"/findByUserId"</span>)
     <span class="hljs-function"><span class="hljs-keyword">public</span> UserDTO <span class="hljs-title">findByUserId</span><span class="hljs-params">(@RequestParam(<span class="hljs-string">"userId"</span>)</span> <span class="hljs-keyword">final</span> String userId) </span>{
         UserDTO userDTO = <span class="hljs-keyword">new</span> UserDTO();
         userDTO.setUserId(userId);
         userDTO.setUserName(<span class="hljs-string">"hello world"</span>);
         <span class="hljs-keyword">return</span> userDTO;
     }    
  }
</code></pre>
<ul>
<li>example （2）：<code>/order/save</code> will be handled by gateway, and <code>/order/findById</code> won't.</li>
</ul>
<pre><code class="language-java"> <span class="hljs-meta">@RestController</span>
 <span class="hljs-meta">@RequestMapping</span>(<span class="hljs-string">"/order"</span>)
 <span class="hljs-meta">@SoulSpringCloudClient</span>(path = <span class="hljs-string">"/order"</span>)
 <span class="hljs-keyword">public</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">OrderController</span> </span>{
 
     <span class="hljs-meta">@PostMapping</span>(<span class="hljs-string">"/save"</span>)
     <span class="hljs-meta">@SoulSpringMvcClient</span>(path = <span class="hljs-string">"/save"</span>)
     <span class="hljs-function"><span class="hljs-keyword">public</span> OrderDTO <span class="hljs-title">save</span><span class="hljs-params">(@RequestBody <span class="hljs-keyword">final</span> OrderDTO orderDTO)</span> </span>{
         orderDTO.setName(<span class="hljs-string">"hello world save order"</span>);
         <span class="hljs-keyword">return</span> orderDTO;
     }

     <span class="hljs-meta">@GetMapping</span>(<span class="hljs-string">"/findById"</span>)
     <span class="hljs-function"><span class="hljs-keyword">public</span> OrderDTO <span class="hljs-title">findById</span><span class="hljs-params">(@RequestParam(<span class="hljs-string">"id"</span>)</span> <span class="hljs-keyword">final</span> String id) </span>{
         OrderDTO orderDTO = <span class="hljs-keyword">new</span> OrderDTO();
         orderDTO.setId(id);
         orderDTO.setName(<span class="hljs-string">"hello world findById"</span>);
         <span class="hljs-keyword">return</span> orderDTO;
     }
 }
</code></pre>
<ul>
<li>start your service, get the log <code>dubbo client register success</code>，then your interface has been added with soul gateway successfully.</li>
</ul>
<h2>plugin setting</h2>
<ul>
<li>enable Spring Cloud plugin in <code>soul-admin</code>.</li>
</ul>
<h2>User request</h2>
<ul>
<li>
<p>Send the request as before, only two points need to notice.</p>
</li>
<li>
<p>firstly，the domain name that requested before in your service, now need to replace with gateway's domain name.</p>
</li>
<li>
<p>secondly，soul gateway needs a route prefix which comes from <code>contextPath</code>, it configured during the integration with gateway, you can change it freely in divide plugin of <code>soul-admin</code>, if your familiar with it.</p>
</li>
</ul>
<pre><code class="language-yaml">
<span class="hljs-comment"># for example, your have an order service and it has a interface, the request url: http://localhost:8080/test/save</span>

<span class="hljs-comment"># now need to change to：http://localhost:9195/order/test/save</span>

<span class="hljs-comment"># we can see localhost:9195 is the gateway's ip port, default port number is 9195 ，/order is the contextPath in your config yaml file. </span>

<span class="hljs-comment"># the request of other parameters don't change.</span>

<span class="hljs-comment"># Any questions, pls join the group and we can talk about it.</span>

</code></pre>
<ul>
<li>then you can visit, very easy and simple。</li>
</ul>
</div></section><footer class="footer-container"><div class="footer-body"><img src="/website/img/dromara.png"/><div class="cols-container"><div class="col col-12"><h3>Disclaimer</h3><p>Any unit or individual reprint all relevant information of this website, please indicate the source.</p></div><div class="col col-6"><dl><dt>Document</dt><dd><a href="/website/en-us/docs/soul/soul.html" target="_self">Overview </a></dd><dd><a href="/website/en-us/docs/soul/soul.html" target="_self">Stat up</a></dd><dd><a href="/website/en-us/docs/soul/soul.html" target="_self">Developer Guide</a></dd></dl></div><div class="col col-6"><dl><dt>Resource</dt><dd><a href="/website/en-us/blog/index.html" target="_self">Blog</a></dd><dd><a href="/website/en-us/community/index.html" target="_self">Community</a></dd></dl></div></div><div class="copyright"><span>Copyright ©2020 xiaoyu@apache.org by xiaoyu</span></div></div></footer></div></div>
	<script src="https://f.alicdn.com/react/15.4.1/react-with-addons.min.js"></script>
	<script src="https://f.alicdn.com/react/15.4.1/react-dom.min.js"></script>
	<script>
		window.rootPath = '/website';
  </script>
	<script src="/website/build/documentation.js"></script>
</body>
</html>